Allow crypto.createPrivateKey() and APIs that consume private keys, such as crypto.sign(), crypto.privateDecrypt(), crypto.diffieHellman(), and crypto.decapsulate(), to load private keys through configured OpenSSL STORE loaders using WHATWG URL objects.

This supports direct URL input:

import { createPrivateKey } from 'node:crypto';

const key = createPrivateKey(
  new URL('file:///path/to/private-key.pem'),
);

It also supports object input with an optional passphrase or PIN and OpenSSL property query:

import { createPrivateKey, sign } from 'node:crypto';

const key = createPrivateKey({
  key: new URL('pkcs11:token=node;object=signing-key;type=private'),
  passphrase: process.env.PKCS11_PIN,
  properties: 'provider=pkcs11',
});

const signature = sign('sha256', Buffer.from('payload'), key);

The provider implementing the STORE loader must already be loaded in Node.js' default OpenSSL library context, for example through OpenSSL configuration. This API does not load providers.

passphrase is forwarded to the loader as its passphrase or PIN. properties is an OpenSSL property query used to select the STORE loader; it is not appended to the URL and is distinct from provider-specific URI parameters.

Why URL?

A URL distinguishes an external key reference from existing key material. Strings, buffers, typed arrays, and formatted objects retain their existing PEM, DER, JWK, and raw-key semantics. This avoids adding STORE loading to the key import/export format namespace.

URL input is accepted only in private-key contexts. A public key can be derived by first loading the private key and passing the resulting KeyObject to crypto.createPublicKey().

The resulting provider-backed key is an ordinary KeyObject and interoperates with existing private-key operations, key metadata, public-key derivation, and toCryptoKey() where supported by the key algorithm and provider. Provider policy continues to control permitted operations and private-key exportability.

The native STORE-loading path is available with OpenSSL >= 3.

Permission model

STORE loading adds the global crypto.store permission, enabled with --allow-crypto-store and exposed through the runtime permission APIs:

process.permission.has('crypto.store'); // true
process.permission.drop('crypto.store');
process.permission.has('crypto.store'); // false

This permission grants broad authority to configured STORE loaders. Loaders may access files, devices, tokens, or the network, and that access is not constrained by the fs.read, fs.write, or net permission scopes.

This broad capability matches OpenSSL's behavior: STORE loaders perform their own I/O, and OpenSSL may try its file loader before another loader for opaque URIs.

When STORE access is denied, Node.js redacts the URI from the permission error resource and permission diagnostics.

Passphrases and errors

Credentials should be supplied through passphrase rather than embedded in the URI.

If OpenSSL requests a passphrase and none was provided, Node.js throws ERR_MISSING_PASSPHRASE, matching existing encrypted private-key import behavior. Incorrect passphrases and provider failures continue to surface as OpenSSL errors.

Node.js redacts URIs from its own permission-denial errors. Errors reported by OpenSSL or a provider after loading begins may still include the URI.